Skip to content

docs(overview): fix terminology and improve clarity for developer onboarding#20832

Open
Giri-Aayush wants to merge 1 commit into
AztecProtocol:nextfrom
Giri-Aayush:docs/overview-terminology-clarity-fixes
Open

docs(overview): fix terminology and improve clarity for developer onboarding#20832
Giri-Aayush wants to merge 1 commit into
AztecProtocol:nextfrom
Giri-Aayush:docs/overview-terminology-clarity-fixes

Conversation

@Giri-Aayush
Copy link
Copy Markdown

Summary

This PR improves the Aztec Overview page from the perspective of a developer who is new to Aztec. As someone onboarding into the ecosystem, I noticed several terminology inconsistencies and areas where the language could better guide newcomers through Aztec's unique concepts.

Changes

  • Terminology: Replace incorrect "Public VM" references with "AVM" (Aztec Virtual Machine) and "sequencer" to align with official architecture docs, diagrams, and the public execution documentation
  • Grammar: "A incoming/outgoing" → "An", "get start" → "get started", "follow" → "follows", "transactions" → "functions" where referring to execution context
  • Execution section: Restructured from a dense paragraph into scannable bullet points with a clear directional flow (private first, then public)
  • Private state section: Rewrote with a cash analogy to help developers unfamiliar with UTXO models understand notes and nullifiers intuitively. Reordered to explain public state first (familiar to Solidity devs) before introducing the new UTXO concepts
  • Account abstraction: Improved wording for natural readability
  • PXE/AVM separation: Consistent use of "AVM" instead of mixing "Public VM" and "AVM"

Why both docs-developers/ and versioned docs?

Applied changes to both docs-developers/overview.md (next version) and developer_versioned_docs/version-v4.0.0-devnet.2-patch.0/overview.md (current stable devnet). The fixes improve clarity for current users on the stable version too. Happy to drop the versioned docs changes if the team prefers to keep those frozen.

Test plan

  • Verified locally with yarn start that both devnet and next overview pages render correctly
  • Confirmed terminology matches official architecture diagrams and the public execution, transactions, and call types documentation

…eloper onboarding

- Replace incorrect "Public VM" with "AVM" and "sequencer" to match
  official architecture documentation
- Fix grammar: "A incoming/outgoing" to "An incoming/outgoing"
- Fix grammar: "get start" to "get started", "follow" to "follows"
- Fix terminology: "transactions" to "functions" for execution context
- Restructure wall of text execution section into scannable bullet points
- Rewrite private state section with cash analogy to help developers new
  to UTXO models understand notes and nullifiers
- Reorder state section: public first (familiar to Solidity devs), then
  private with clear explanation of why nullifiers exist
- Improve account abstraction wording for natural readability
- Applied to both docs-developers (next) and versioned devnet docs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant